QuickTime 4 Reference

AddSequenceElement

Listing 4 shows AddSequenceElement , a routine that adds a leaf atom of type kTweenSequenceElement to a container. The sequenceAtom that you pass in is the newSequenceAtom parameter returned by AddSequenceTweenAtom. Each time you call AddSequenceElement , a sequence tween element is added to the end of the list of elements. The tween toolbox organizes the list in index order, with IDs ignored.

Each element has a duration that is some percentage of the tween's duration. The element's duration is its endPercent value minus the previous element's endPercent value. For example, if you wanted three elements to last 0.25, 0.25, and 0.5 of the tween's duration, then the elements' endPercent values should be set to 0.25, 0.5, and 1. The elements tell the tween toolbox which tweenAtom and dataAtom to switch to.

The tweenAtomID is the ID of a kTweenEntry atom within the sequenceAtom . The dataAtomID is the ID of a kTweenData atom. The kTweenData atom is a child atom of the specified tweenAtom . Usually you only need to create one tweenAtom with multiple data atoms. Some tweener types (such as 3D tweeners) use child atoms of the tweenEntry atom for initialization, so in these cases you usually create a tweenAtom with one dataAtom per sequence entry.

Listing 4 Utility routine AddSequenceElement



 
OSErr AddSequenceElement( QTAtomContainer container, QTAtom sequenceAtom,

    Fixed endPercent, QTAtomID tweenAtomID, QTAtomID dataAtomID, 

    QTAtom *newSequenceElementAtom )

{

    TweenSequenceEntryRecord    entry;



    if ( (! container) || (endPercent > (1L<<16)) || (tweenAtomID == 0)

                            || (dataAtomID == 0) ){ return paramErr; }



    entry.endPercent        = endPercent;

    entry.tweenAtomID       = tweenAtomID;

    entry.dataAtomID        = dataAtomID;



    // adds at end of list by index, with any unique atom id

    return QTInsertChild( container, sequenceAtom, kTweenSequenceElement,

                0, 0, sizeof(entry), &entry, newSequenceElementAtom );

}